<body>
<p>Vimoir is a server and a library for building Netbeans applications interfaced
with Vim.

<p> Use the vimoir library to interface a java or a python application with Vim
through the Netbeans protocol. The client application implements the
{@link vimoir.netbeans.NetbeansEventHandler} interface which maps Vim Netbeans
events to methods. The vimoir library takes care of the details of the protocol
such as registering buffers with a <i>bufID</i>, managing <i>seqno</i> command
sequence numbers, instantiating the client class on each new connection request
from a Vim instance and managing the corresponding concurrent Netbeans socket
connections.

<h4>The client class</h4>
<p> To develop a client, one must implement a class:

<ul>
<li>The class constructor signature has a single argument which is an instance
of the {@link vimoir.netbeans.NetbeansSocket} interface.

<li>The class implements the NetbeansEventHandler interface where are defined
the methods used to process Netbeans events and the class may also optionally
implement <code>cmd_&lt;keyName&gt;()</code> methods (see below). On the
occurence of an exception not captured by the client, the library logs the
exception and its backtrace and closes the socket.
</ul>

<p>The NetbeansSocket object provides the methods to send Netbeans commands and
functions. The server instantiates a NetbeansSocket object and the client class
on each new incoming connection. The client class is defined by its qualified
name which is the value of the <code>vimoir.netbeans.java.client</code>
property. On each new connection, the server re-reads the
<code>vimoir.properties</code> file content, so that it is possible to
dynamically update the configuration data of the server without having to stop
it.

<h4>The NetbeansBuffer objects</h4>
<p> A {@link vimoir.netbeans.NetbeansBuffer} object is automatically
instantiated and registered to Netbeans by the Netbeans socket with the
<code>putBufferNumber</code> command on the first <code>fileOpened</code> event
for this buffer.

<p> A NetbeansBuffer is never directly instantiated by the application, instead
 use the {@link vimoir.netbeans.NetbeansSocket#get_buffer} method to create a
 new NetbeansBuffer object or to get an existing one.

<h4>The nbkey Vim command</h4>
<p> The syntax of <code>nbkey</code> Vim commands is <code>:nbkey keyName
args...</code>. The Netbeans <code>keyAtPos</code> event generated by this Vim
command is dispatched to the client class <code>cmd_&lt;keyName&gt;()</code>
method when such a method has been implemented, or to the NetbeansEventHandler
<code>default_cmd_processing()</code> method otherwise.

<h4>Threads</h4>
<p>The library runs in a single thread of execution. When a time consuming task
(such as opening a database for example) must be undertaken on the occurence of
a Netbeans event, this task should be run in its own worker thread, so as not
to block other I/O operations.

</body>
